---
sidebar_label: To Remote Schema
sidebar_position: 3
description: Adding Remote Schema relationships with Postgres tables in Hasura
keywords:
  - hasura
  - docs
  - remote schema relationship
  - remote join
  - graphql join
  - remote schema
  - data federation
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Thumbnail from '@site/src/components/Thumbnail';
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';

# Remote Schema to Remote Schema Relationships

## Introduction

Remote Schema to Remote Schema relationships (a.k.a GraphQL joins) extend the concept of joining data across tables, to
joining across remote GraphQL sources. Once you create relationships between types from the GraphQL schemas, you can
then "join" them by running GraphQL queries.

These APIs can be custom GraphQL servers you write, third party SaaS APIs, or even other Hasura instances.

Because Hasura is meant to be a GraphQL server that you can expose directly to your apps, Hasura also handles security
and authorization while providing remote joins.

:::tip Supported from

Relationships from Remote Schema to Remote Schema are supported from versions `v2.6.0` and above.

:::

## Create Remote Schema relationships

### Step 1: Add two Remote Schemas

Add two Remote Schemas as described [here](/remote-schemas/adding-schema.mdx), if the schemas aren't already added.

### Step 2: Define and create the relationship

The following fields can be defined for a Remote Schema relationship:

- **Name**: Define a name for the relationship.
- **Remote Schemas**: Select two Remote Schemas among all the ones you've created.
- **Configuration**: Set up the join configuration, to inject values as input arguments of the Remote Schema field.
  - **From column**: Input injected from table column values.
  - **From static value**: Input injected from a static value of your choice.

For example, let's assume that our first Remote Schema `order-remote-schema` has a field `order(id int, user_id int)`
and our second Remote Schema `user-remote-schema` - which is another GraphQL API - has a field
`user(id int, name text)`. Now we want to create a relationship between the `order` field of the first Remote Schema and
the `user` field of the second Remote Schema.

1.  We name the relationship `user`.
2.  We select the source type `Order` of the Remote Schema that we'd like to join.
3.  We select `user-remote-schema` as the reference Remote Schema.
4.  We select `id` as the source field and `user_id` as the from field.

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

- Head to the `Remote Schema -> [remote-schema-name] -> Relationships` tab.
- Click the `Add a new relationship` button.

  <Thumbnail
    src="/img/schema/create-relationship-from-remote-schema.png"
    alt="Opening the remote relationship section"
    width="1000px"
  />

- Define the relationship and hit `Add Relationship`.

  <Thumbnail src="/img/schema/configure-relationship-rs-to-rs.png" alt="Defining the relationship" width="800px" />

</TabItem>
<TabItem value="cli" label="CLI">

Update the `remote_schemas.yaml` file in the `metadata` directory:

```yaml {4-16}
- name: order-remote-schema
  definition:
    url: https://remote-schema-endpoint.com
  remote_relationships:
    - relationships:
        type_name: Order
        name: user
        - definition:
            to_remote_schema:
              remote_schema: user-remote-schema
              lhs_fields:
                - user_id
              remote_field:
                user:
                  arguments:
                    id: $user_id
```

Apply the Metadata by running:

```bash
hasura metadata apply
```

</TabItem>
<TabItem value="api" label="API">

You can add a Remote Schema relationship by using the
[create_remote_schema_remote_relationship](/api-reference/metadata-api/remote-relationships.mdx#metadata-create-remote-schema-remote-relationship)
Metadata API and update it by using the
[update_remote_schema_remote_relationship](/api-reference/metadata-api/remote-relationships.mdx#metadata-update-remote-schema-remote-relationship)
Metadata API:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "create_remote_schema_remote_relationship",
  "args": {
    "name": "user",
    "remote_schema": "order-remote-schema",
    "type_name": "Order",
    "definition": {
      "to_remote_schema": {
        "remote_schema": "user-remote-schema",
        "lhs_fields": ["user_id"],
        "remote_field": {
          "user": {
            "arguments": {
              "id":"$user_id"
            }
          }
        }
      }
    }
  }
}
```

</TabItem>
</Tabs>

### Step 3: Explore with GraphiQL

In the `API` tab, test out your Remote Schema relationship.

<GraphiQLIDE
  query={`query {
  order_remote_schema {
  	order (id: 1) {
    	id
    	user_id
    	user {
      	id
      	name
    	}
  	}
  }
}`}
  response={`{
  "data": {
    "order_remote_schema": {
      "order": {
        "id": 1,
        "user_id": 2,
        "user": {
          "id": 2,
          "name": "Bob"
        }
      }
    }
  }
}`}
/>
